home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 August: Tool Chest / Dev.CD Aug 98 TC.toast / Tool Chest / Development Kits / MPW etc. / Debuggers / SADE / SADE 1.4a3 / SADE New User WorkSheet next >
Encoding:
Text File  |  1992-07-10  |  12.3 KB  |  255 lines  |  [TEXT/sade]
  1. ##########################################################################################
  2. #    Symbolic Application Debugging Environment 1.4
  3. #
  4. #    copyright Apple Computer, Inc. 1987-1992
  5. #    All rights reserved.
  6. #
  7. ##########################################################################################
  8. # You may be able to use Sade using only Menu commands.  However, if you are
  9. # doing some things repeatedly, you may save time by learning to write some
  10. # commands, saving them, using them the next time around.
  11. # This worksheet contains some commands you might like to try.
  12. # It also contains a section on how to debug MPW tools, and MacApp code.
  13. #
  14. ###############################################################################
  15. # Execute commands in the Worksheet as in MPW with the Enter key.  With a command
  16. selected, you can also click on the status box in the upper left hand corner;
  17. which has identical effect.
  18.  
  19. Version      # To display SADE's version information; or use About SADE in Apple menu.
  20.  
  21. Help        # Get a list of help topics; or use SADE Help menu command in Find menu.
  22.  
  23. # When you compile and link your application, specify the -sym on option to create
  24. # the file containing symbol information (.SYM) that SADE requires for debugging. 
  25.  
  26. # Note that the following commands use one of the sample applications that comes
  27. # with the SADE disk. Substitute a different sample application or one of your own
  28. # applications if you wish.
  29.  
  30. # Identify the target application to debug and its symbol file:
  31.     Directory 'SADE:SADE Tutorials:CExamples:C Tutorial 1'
  32. #    Sourcepath 'pathname1','pathname2'    # This command is not necessary with Sample1
  33.                                         # because its source is in one directory. Use
  34.                                         # SourcePath only if your source files are in 
  35.                                         # multiple directories or in a different 
  36.                                         # directory than your application.
  37.     Target 'Sample1'    # assumes symbol file is 'Sample1.SYM'
  38.  
  39. # You will see that Target not only identifies the application but launches it, opens
  40. # the source file, and breaks at the first statement of the main program.
  41.  
  42. # Now select a statement of interest; e.g., DoMenuCommand (use the Mark menu), and 
  43. # choose the Go Til command from the SourceCmds menu. SADE sets a temporary 
  44. # breakpoint on DoMenuCommand and resumes operation of Sample1 (the traffic light 
  45. # appears). SADE will be reentered when the breakpoint is encountered; in this case, 
  46. # choose Red Light from the Traffic menu and SADE highlights DoMenuCommand in the 
  47. # source file.
  48.  
  49. # Now choose a variable to watch, e.g., gStopped, which tells whether the light is
  50. # Red (TRUE) or green (FALSE); highlight gStopped here and select Add Watch Variable
  51. # from the Variables menu. SADE opens a window displays its current value. SADE will 
  52. # also show its new value whenever you step. 
  53.  
  54. # Now step the program using Step in the SourceCmds menu. If you want to step into a
  55. # routine use the Step Into menu command. For example, after 4 or 5 steps you can 
  56. # step into the SetLight routine when SetLight (FrontWindow(), false); is highlighted.
  57. # Within the SetLight routine, gStopped should change to 0. 
  58.  
  59. # To remove Sample1 as the target, issue this command:
  60.     Kill
  61.  
  62. ###############################################################################
  63. # When your application is running, you can suspend it and enter SADE by 
  64. # pressing <command-option> <SADEKey>.
  65. # The default SADEKey is <numeric-key-pad-period>.
  66. # To change it, modify and execute the following:
  67.  
  68. SADEKey <new key code>
  69.  
  70. # See Inside Macintosh Volume 5, pages 191-192 for the key codes for the various keyboards.
  71.  
  72. ###############################################################################
  73. # Debugging Object Pascal and MacApp
  74.     MacApp methods are supported.  Within methods, references to the instance 
  75.     variables of the object can be made without qualifying those references by SELF.
  76.     These free references to instance variables can also be done in C++ member 
  77.     functions.
  78.     
  79.     A SADE variable, BreakIfNoSource, defaults to 0. When 0, a Step Into will 
  80.     continue stepping until there is source statement information available for the 
  81.     instruction at the program counter. Stepping into a method call will break 
  82.     at the first instruction of the method. The down side is that if SADE steps into 
  83.     something without statement information, it will appear SADE has hung.  It hasn't, 
  84.     it's just very busy executing your code 2 to 3 orders of magnitude slower than 
  85.     normal.  This down side should only affect you if you step into code which has
  86.     been built without symbols.  Should you do so, you have a choice of waiting for 
  87.     completion of stepping or rebooting.  Setting BreakIfNoSource to 1 will make 
  88.     SADE break when no source information is available for the PC.
  89.     
  90.     To step into a method use the Step Into menu item from the SourceCmds menu 
  91.     (Source vs Asm checked in SourceCmds) or the Step Line Into command and options.
  92.     To avoid stepping through MacApp's method dispatch code, you should assemble
  93.     MacApp's ≈.a files with "-SYM OFF".  Also, UObject.p.o and UMacAppUtilities.p.o
  94.     should be compiled with "-SYM OFF" because routines in these files are called as
  95.     part of the method dispatch.
  96.     
  97.     Follow these simple steps when debugging MacApp code with SADE.  Assume the
  98.     target is the MacApp sample program DemoDialogs:
  99.     
  100.     (1)    In MPW, set the directory to the location of your sourcefiles and build your 
  101.     application with symbol information:
  102.             directory "hd:MacApp® 2.0.1:Examples:DemoDialogs:"
  103.             mabuild -sym -autobuild DemoDialogs
  104.     The -autobuild option will build the MacApp libraries if necessary.
  105.     
  106.     (2) Double click on the DemoDialogs.sym file from the Finder.  The file should
  107.     be located in the newly created .NoDebug Sym folder within the sources folder.
  108.     This will launch SADE, set the directory and sourcepath and target DemoDialogs.
  109.     However, SADE still does not know where the MacApp libraries are located and so
  110.     you will be prompted to locate them if you attempt to step into a MacApp method
  111.     or suspend execution in a MacApp method.
  112.     
  113.     You may wish to launch SADE and setup the directory and sourcepath variables
  114.     yourself before targeting DemoDialogs. To do so, execute the following commands
  115.     from SADE:
  116.         directory "hd:MacApp® 2.0.1:Examples:DemoDialogs:.NoDebug Sym:"
  117.         Sourcepath    "hd:MacApp® 2.0.1:Examples:DemoDialogs:", ∂
  118.                     "hd:MacApp® 2.0.1:Libraries:"
  119.         Target 'DemoDialogs'
  120.         
  121.     The file MDemoDialogs.cp should now be open and the program counter should be at
  122.     the first statement: void main ()
  123.         
  124.  
  125. ###############################################################################
  126. # Low-level Debugging
  127. # You can set SourceCmds menu to Asm Debugging.
  128. # If you use Step menu command now, SADE executes one instruction at a time rather 
  129. # than one source statement at a time.
  130.  
  131. # Here are some commands you can use for low-level debugging:
  132.     Stack                        # Show the address of, owner, and caller of all 
  133.                                 # stack frames- see also the section below on
  134.                                 # 'SADE Example Scripts' for a useful script to
  135.                                 # do stack crawls based on A7 rather than A6
  136.  
  137.     Disasm pc 10                # Disassemble 10 instructions starting from the pc
  138.     
  139.     Disasm myProc.(1)             # Disassemble 20 (the default) instructions starting
  140.                                 # from the first statement of procedure myProc
  141.  
  142.     Dump a0 64                    # Display 64 bytes beginning at location pointed to
  143.                                 # by register a0
  144.     
  145.  
  146. # Macintosh System Structures
  147.  
  148.     heap                        # Display the heap pointed at by theZone
  149.     heap check                    # Validate the heap pointed at by theZone
  150.     resource                       # displays all open resource maps in target application
  151.  
  152.     windowList^                    # Display FrontWindow as a grafPort
  153.     ^WindowRecord(windowList)^    # Display FrontWindow as a windowRecord
  154.     *(WindowRecord *)(windowList)    # doing the same with a C expression
  155.  
  156. ###############################################################################
  157. # Source Level Debugging (Set SourceCmds to Source Debugging)
  158. # If you use Step menu command, SADE steps one source statement at a time. Here is
  159. # a procedure for stepping a given number of times; note the use of the onEntry 
  160. # keyword, which tells SADE what to do after each step; in this case, take another 
  161. # step.
  162. define StepCount
  163. proc __Step__
  164.     if (StepCount > 0)
  165.         StepCount := StepCount - 1;
  166.         step onentry __step__
  167.     end
  168. end
  169. proc StepN(__n__)
  170.     StepCount := __n__
  171.     Step OnEntry __Step__
  172. end
  173.  
  174. StepN (3)    # Step three times
  175.  
  176. #  After you're finished, you may wish to undefine StepCount.
  177. undefine StepCount
  178.  
  179.  
  180. ###############################################################################
  181. # To debug an MPW tool (using the example tool Count), compile and link the tool 
  182. # with symbolic information (-sym on|full). Be sure to specify the file type and 
  183. # creator when you Link an MPW tool:
  184.     Link -t 'MPST' -c 'MPS ' -sym on
  185.             
  186. # From the Finder, double-click on the tool's SYM file. This will launch SADE, set the
  187. # directory and target the tool. As long as MPW is still running, SADE will make MPW
  188. # the frontmost application. Otherwise, SADE will prompt you to locate the MPW Shell 
  189. # and then it will launch MPW. You may then run your tool from MPW and SADE will 
  190. # execute it, stopping at the first line of the main program.
  191.  
  192. # Another way of targeting a tool would be to execute the following commands from 
  193. # SADE to set the directory and target the tool.  After MPW is launched, run the tool.
  194.  
  195.     Directory "hd:mpw:Examples:CExamples:"
  196.     Target "hd:mpw:mpw shell" using "Count.SYM"
  197.     
  198. # To remove the tool as the target, kill the tool using either the Kill menu
  199. # command (which calls KillTool) or issue KillTool from the SADE worksheet. 
  200. # Do not issue the Kill command from the worksheet.  This will kill MPW.
  201. # KillTool will shutdown the tool and leave MPW running, so you can continue to 
  202. # work in MPW if you wish. 
  203.     KillTool
  204.  
  205.  
  206. ###############################################################################
  207. # The folder 'SADE Example Scripts' contains files with examples of the SADE language.
  208. # You might find these interesting if you are attempting to write your own scripts.
  209. # To execute these scripts, you must first target an application.  Then set the  
  210. # directory to the folder containing the scripts.
  211.  
  212. Directory concat (SADEDir,'SADE Example Scripts:')    # SADEDir is defined in SADEStartup
  213.  
  214. # Then select any line beginning with 'execute' and press Enter; commands nested
  215. # under the execute line represent procedures defined in the script files and
  216. # can then be run as well.
  217.  
  218. Execute 'MiscProcs'
  219.     DisplayFCBs                # Displays information about all open files
  220.     displaywindowlist        # Displays the name of each open window in the target application.
  221.     InterList('routine name', 'output filename')    # interleaves statements and associated instructions
  222.     factorial (20)            # Evaluate the factorial of 20 and printout the results
  223.  
  224. Execute 'Resource'
  225.     ResMap "CODE"            # Display information about all CODE resources.
  226.     ResMap                    # SLOWLY mimics the resource command
  227.     ResVerify                # mimics the resource check command
  228.  
  229. Execute 'sc7'
  230.     StackCrawl7                # Display a possible calling chain sequence.  There is
  231.                             # also a macro 'sc7' defined in the script which executes
  232.                             # stackcrawl7.
  233.     
  234.  
  235. ###############################################################################
  236. # Command Key Equivalents: The AddMenu command allows you to add new menus to the
  237. # SADE menu bar. You can optionally add a key equivalent for any of the menus you
  238. # create by preceding the key with a frontslash. Since the SourceCmds and Variables
  239. # menus are both defined in the file SADEStartup, you can change the key equivalents  
  240. # for the commands defined in those menus if you wish. 
  241.  
  242. # For instance, the key equivalent for Show Dereferenced Value is Command-◊, or 
  243. # Command-Option-Shift-V. If you find this a difficult key combination to press, you 
  244. # may change it by replacing '◊' with a different character. The best place to make
  245. # this change is in a SADEUserStartup•≈ file that you create. Since any such file will
  246. # be executed after SADEStartup when SADE is launched, your changes will overwrite the 
  247. # same command defined in SADEStartup, but will leave SADEStartup untouched.
  248.  
  249. # Show Dereferenced Value as defined in SADEStartup:
  250. addmenu 'Variables'  'Show Dereferenced Value /◊'    'ShowDereferencedValue(selection(ActiveWindow))'
  251.             
  252. # Create a file SADEUserStartup•MyName and add this line to change the key equivalent only.
  253. # This example changes the key equivalent to Command-9.
  254. addmenu 'Variables'  'Show Dereferenced Value /9'    'ShowDereferencedValue(selection(ActiveWindow))'
  255.